Dashing a Shape (IM: XG)

Inside Macintosh: QuickDraw GX Graphics /: Chapter 3 - Geometric Styles / Using Geometric Styles

Dashing a Shape
To add a dash shape along the contours of another shape, you must create a dash structure. The dash structure has five fields:

the dash attributes, which modify the way the shape is dashed
the dash shape, which contains the shape to use as the dashes
the dash advance, which determines the number of points between the start of one dash and the start of the next
the dash phase, which determines how far into the advance the dashing should start
the dash scale, which you can use to counteract the automatic scaling of the dash shape

The sample function in Listing 3-13 creates a curve shape dashed with diamonds. First, it creates the curve shape and the diamond shape. The diamond shape has a height and a width of 30.0 points.
The sample function then creates a dash structure for the diamond dashes, and calls the GXSetShapeDash function to set the dash property of the curve shape's style object.
Listing 3-13 Creating a curve shape dashed with diamonds
void CreateDashedCurve(void)
{
   gxShape  aCurveShape, aDiamondShape;

   static gxCurve curveGeometry = {ff(50), ff(125), 
                                   ff(125), 0, 
                                   ff(250), ff(125)};
      
   static long diamondGeometry[] = {1, /* number of contours */
                                    4, /* number of points */
                                    ff(0), ff(15), 
                                    ff(15), fl(0),
                                    ff(0), -ff(15), 
                                    -ff(15), ff(0)}; 

      
   gxDashRecord theDashRecord;
   
   
   aCurveShape = GXNewCurve (&curveGeometry);

   aDiamondShape = GXNewPolygons((gxPolygons *) diamondGeometry);
      
   theDashRecord.attributes = gxNoAttributes;  
   theDashRecord.dash = aDiamondShape;
   theDashRecord.advance = ff(40); 
   theDashRecord.phase = 0; 
   theDashRecord.scale = ff(30); 

   GXSetShapeDash(aCurveShape, &theDashRecord);
   
   GXDisposeShape(aDiamondShape);
      
   GXSetShapePen(aCurveShape, ff(30));
   
   GXDrawShape(aCurveShape);
   
   GXDisposeShape(aCurveShape);
}
Note
As with caps and joins, QuickDraw GX copies only the geometric information of the dash shape into the dash property of the style object; it does not copy the entire dash shape. For this reason, the dash shape must be in its primitive form. Once you have called GXSetShapeDash, you are free to change the original dash shape without affecting the dashes of the dashed shape.
Notice that this sample function sets the dash advance to 40. Since the diamond shape is 30 points wide, this dash advance allows for 10 points between dashes. The dash phase is set to 0, which indicates that the origin of the first dash should be aligned with the beginning of the curve contour exactly.
Since QuickDraw GX scales dashes (perpendicularly to the dashed contour) by the pen width, the dashes in this example would be 900 points from tip to tip, as the diamond shape itself is 30 points high and the pen width of the curve is also 30 points. However, the sample function sets the dash scale to 30, by which QuickDraw GX scales the dashes down (again, perpendicularly to the dashed contour), which leaves the diamond shapes with their original size.
Figure 3-59 shows the result of the CreateDashedCurve sample function.
Figure 3-59 A dashed curve

If you provide a smaller value for the dash scale, QuickDraw GX scales the dashes up in the direction perpendicular to the dashed contour. For example, if you provide a dash scale half as large:
theDashRecord.scale = ff(15);
the dashes become twice the size in the direction perpendicular to the curve, as shown in Figure 3-60.
Figure 3-60 A curve with scaled dashes

The dashes are now actually wider than the pen width of the curve. You can set the clip dash attribute to draw only the parts of the dashes that lie within the curve's pen width. For example, adding this line of code to the sample function:
theDashRecord.attributes = gxClipDash;  
creates the shape shown in Figure 3-61.
Figure 3-61 A curve with clipped dashes

Notice that QuickDraw GX not only clips the dashes to the width of the curve, but also clips them at the ends of the curve. To shift the dashes along the curve so that you see the whole first dash, you can adjust the dash phase. For example, this line of code:
theDashRecord.phase = GXFloatToFract(0.50); 
shifts the dashes forward one half of the dash advance. Since the dash advance in this case is 40, the dashes are shifted forward 20 points, as shown in Figure 3-62.
Figure 3-62 A curve with phased dashes

In this case, adjusting the dash phase is sufficient to cause a whole number of dashes to show. In other cases, you may have to use the auto-advance dash attribute, which is described in the next section.
The sections "The Dash Structure" on page 3-103 and "Dash Attributes" on page 3-105 describe the dash record and dash attributes in more detail, and the section "Getting and Setting Dashes" beginning on page 3-134 describes the functions you can use to manipulate dashes.